IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat2 / standard / sproc.z / sproc

Wrap

Text File | 2002-10-03 | 28.5 KB | 463 lines

SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) NNNNAAAAMMMMEEEE sproc, sprocsp, nsproc - create a new share group process CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttyyyyppppeeeessss....hhhh>>>> ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////pppprrrrccccttttllll....hhhh>>>> ppppiiiidddd____tttt sssspppprrrroooocccc ((((vvvvooooiiiidddd ((((****eeeennnnttttrrrryyyy)))) ((((vvvvooooiiiidddd ****)))),,,, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnnhhhh,,,, ............))));;;; Type of optional third argument: vvvvooooiiiidddd ****aaaarrrrgggg;;;; ppppiiiidddd____tttt sssspppprrrrooooccccsssspppp ((((vvvvooooiiiidddd ((((****eeeennnnttttrrrryyyy)))) ((((vvvvooooiiiidddd ****,,,, ssssiiiizzzzeeee____tttt)))),,,, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnnhhhh,,,, vvvvooooiiiidddd ****aaaarrrrgggg,,,, ccccaaaaddddddddrrrr____tttt sssspppp,,,, ssssiiiizzzzeeee____tttt lllleeeennnn))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The _ssss_pppp_rrrr_oooo_cccc and _ssss_pppp_rrrr_oooo_cccc_ssss_pppp system calls are a variant of the standard _ffff_oooo_rrrr_kkkk(2) call. Like _ffff_oooo_rrrr_kkkk, the _ssss_pppp_rrrr_oooo_cccc calls create a new process that is a clone of the calling process. The difference is that after an _ssss_pppp_rrrr_oooo_cccc call, the new child process shares the virtual address space of the parent process (assuming that this sharing option is selected, as described below), rather than simply being a copy of the parent. The parent and the child each have their own program counter value and stack pointer, but all the text and data space is visible to both processes. This provides one of the basic mechanisms upon which parallel programs can be built. The system call _nnnn_ssss_pppp_rrrr_oooo_cccc is no longer supported as an external interface; any calls to it should be replaced with _ssss_pppp_rrrr_oooo_cccc_ssss_pppp. A group of processes created by _ssss_pppp_rrrr_oooo_cccc calls from a common ancestor is referred to as a _s_h_a_r_e _g_r_o_u_p or _s_h_a_r_e_d _p_r_o_c_e_s_s _g_r_o_u_p. A share group is initially formed when a process first executes an _ssss_pppp_rrrr_oooo_cccc or _ssss_pppp_rrrr_oooo_cccc_ssss_pppp call. All subsequent _ssss_pppp_rrrr_oooo_cccc calls by either the parent or other children in this share group will add another process to the share group. In addition to virtual address space, members of a share group can share other attributes such as file tables, current working directories, effective userids and others described below. The three calls differ in just two ways - how the stack for the new process is initialized and in the interpretation of the iiiinnnnhhhh argument. If the argument _s_p is set to NNNNUUUULLLLLLLL then the system will create a stack region for the child. This stack region will not overlap with any other area of the share group's address space. These stack regions grow downward, and are automatically grown if the process accesses new areas of the stack. The _l_e_n argument specifies how much margin (in bytes) the system should attempt to leave for the child's stack. This margin is used when the system attempts to place additional stacks or other virtual spaces (e.g. from _mmmm_mmmm_aaaa_pppp). The system will attempt to leave enough room such that the stack could grow to _l_e_n bytes if it needs to. This margin in no way sets a limit on stack growth nor guarantees a particular stack size. The process can continue to grow its stack up to the maximum permissible size (specified via the resource limit _RRRR_LLLL_IIII_MMMM_IIII_TTTT______SSSS_TTTT_AAAA_CCCC_KKKK) as long as it doesn't run PPPPaaaaggggeeee 1111 SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) into any other virtual space of the share group. Conversely, if the share group's virtual space gets crowded, parts of the stack that haven't yet been claimed could be used for additional stacks or other requested virtual spaces. A minimum of 16K for _l_e_n is recommended. Note that there are no 'red' zones - a process growing its stack could easily start accessing the stack of another process in the share group. If _l_e_n is set to be smaller than the stack size required by the sproc at creation time, an error message indicating that there is "not enough memory to lock stack" may be reported to the system log. This indicates that the system attempted to place the sproc's stack using the _l_e_n value supplied in the _ssss_pppp_rrrr_oooo_cccc_ssss_pppp call, but that the initial size of the sproc's stack would overlap into other portions of the share group's virtual space. The offending sproc will be killed. If _s_p is set to a valid virtual address in the share group then the stack of the new process is set to this value. With this option, the entire responsibility of stack management is the calling process's. The system will no longer attempt to automatically grow the process's stack region. _s_p should point to the top (highest address) of the new stack. It will automatically be rounded down to provide the appropriate alignment. No validity checks are made on _s_p. _ssss_pppp_rrrr_oooo_cccc is equivalent to calling _ssss_pppp_rrrr_oooo_cccc_ssss_pppp with the _s_p argument set to NNNNUUUULLLLLLLL and the _l_e_n argument set to the _r_l_i_m__c_u_r value of the resource limit RRRRLLLLIIIIMMMMIIIITTTT____SSSSTTTTAAAACCCCKKKK. This means that each time a process calls _ssss_pppp_rrrr_oooo_cccc, the total size of each member of the share group increases by the size of the new process's stack. Calling _ssss_pppp_rrrr_oooo_cccc or _ssss_pppp_rrrr_oooo_cccc_ssss_pppp too often, when the stack size is set very large can easily cause the share group to grow larger than the per-process maximum allowable size {_P_R_O_C_S_I_Z_E__M_A_X} [see _iiii_nnnn_tttt_rrrr_oooo(2)]. In this case, the call will fail and return EEEENNNNOOOOMMMMEEEEMMMM. A process with lots of distinct virtual spaces (e.g. lots of files mapped via _mmmm_mmmm_aaaa_pppp(2)) can fragment the calling process's address space such that it is impossible to find a suitable place for the new child's stack. This case will also cause _ssss_pppp_rrrr_oooo_cccc or _ssss_pppp_rrrr_oooo_cccc_ssss_pppp to fail. The new child process resulting from _ssss_pppp_rrrr_oooo_cccc(2) differs from a normally forked process in the following ways: If the PPPPRRRR____SSSSAAAADDDDDDDDRRRR bit is set in _i_n_h then the new process will share ALL the virtual space of the parent, except the PRDA (see below). During a normal _ffff_oooo_rrrr_kkkk(2) or if the PPPPRRRR____SSSSAAAADDDDDDDDRRRR is not set, the writable portions of the process's address space are marked copy-on-write. If either process writes into a given page, then a copy is made of the page and given to the process. Thus writes by one process will not be visible to the other forks. With the PPPPRRRR____SSSSAAAADDDDDDDDRRRR option of _ssss_pppp_rrrr_oooo_cccc_((((_2222_)))), however, all the processes have read/write privileges to the entire virtual space. PPPPaaaaggggeeee 2222 SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) The new process can reference the parent's stack. The new process has its own _p_r_o_c_e_s_s _d_a_t_a _a_r_e_a (PRDA) which contains, among other things, the _p_r_o_c_e_s_s _i_d. Part of the PRDA is used by the system, part by system libraries, and part is available to the application program [see <<<<ssssyyyyssss////pppprrrrccccttttllll....hhhh>>>>]. The PRDA is at a fixed virtual address in each process which is given by the constant PPPPRRRRDDDDAAAA defined in pppprrrrccccttttllll....hhhh. The machine state (general/floating point registers) is not duplicated with the exception of the floating point control register. This means that if a process has enabled floating point traps, these will be enabled in the child process. If created via _ssss_pppp_rrrr_oooo_cccc the new process will be invoked as follows: eeeennnnttttrrrryyyy((((vvvvooooiiiidddd ****aaaarrrrgggg)))) If created via _ssss_pppp_rrrr_oooo_cccc_ssss_pppp the new process will be invoked as follows: eeeennnnttttrrrryyyy((((vvvvooooiiiidddd ****aaaarrrrgggg,,,, ssssiiiizzzzeeee____tttt ssssttttkkkkssssiiiizzzzeeee)))) where _s_t_k_s_i_z_e is the _l_e_n argument the parent passed to _ssss_pppp_rrrr_oooo_cccc_ssss_pppp. In addition to the attributes inherited during the _ssss_pppp_rrrr_oooo_cccc call itself, the _i_n_h flag to _ssss_pppp_rrrr_oooo_cccc can request that the new process have future changes in any member of the share group be applied to itself. A process can only request that a child process share attributes that it itself is sharing. The creator of a share group is effectively sharing everything. These persisting attributes are selectable via the _i_n_h flag: PPPPRRRR____SSSSAAAADDDDDDDDRRRR All virtual space attributes (shared memory, mapped files, data space) are shared. If one process in a share group attaches to a shared memory segment, all processes in the group can access that segment. PPPPRRRR____SSSSFFFFDDDDSSSS The open file table is kept synchronized. If one member of the share group opens a file, the open file descriptor will appear in the file tables of all members of the share group. Note especially that the converse is also true: if one member closes a file, it is closed for all members of the group; this has been known to surprise applications programmers! Note also that there is only one file pointer for each file descriptor shared within a shared process group. PPPPRRRR____SSSSDDDDIIIIRRRR The current and root directories are kept synchronized. If one member of the group issues a _cccc_hhhh_dddd_iiii_rrrr(2) or _cccc_hhhh_rrrr_oooo_oooo_tttt(2) call, the current working directory or root directory will be changed for all members of the share group. PPPPaaaaggggeeee 3333 SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) PPPPRRRR____SSSSUUUUMMMMAAAASSSSKKKK The file creation mask, _u_m_a_s_k is kept synchronized. PPPPRRRR____SSSSUUUULLLLIIIIMMMMIIIITTTT The limit on maximum file size is kept synchronized. PPPPRRRR____SSSSIIIIDDDD The real and effective user and group ids are kept synchronized. To take advantage of sharing all possible attributes, the constant PPPPRRRR____SSSSAAAALLLLLLLL may be used. In addition to specifying shared attributes, the _i_n_h flag can be used to pass flags that govern certain operations within the _ssss_pppp_rrrr_oooo_cccc call itself. Currently two flags are supported: PPPPRRRR____BBBBLLLLOOOOCCCCKKKK causes the calling process to be blocked [see _bbbb_llll_oooo_cccc_kkkk_pppp_rrrr_oooo_cccc(2)] before returning from a successful call. This can be used to allow the child process access to the parent's stack without the possibility of collision. PPPPRRRR____NNNNOOOOLLLLIIIIBBBBCCCC causes the child to not join the C library (libc) arena (see below). If all _ssss_pppp_rrrr_oooo_cccc calls that a process makes specify this flag then the C library arena will never be created. The creation of the C library arena includes the initialization of the per-thread system error value _e_r_r_n_o. No scheduling synchronization is implied between shared processes: they are free to run on any processor in any sequence. Any required synchronization must be provided by the application using locks and semaphores [see _uuuu_ssss_iiii_nnnn_iiii_tttt(3P)] or other mechanisms. If one member of a share group exits or otherwise dies, its stack is removed from the virtual space of the share group. If the process which first created the share group exits, its stack is not removed. This ensures continued access by other share group members to the environment and starting argument vectors. In addition, if the PPPPRRRR____SSSSEEEETTTTEEEEXXXXIIIITTTTSSSSIIIIGGGG option [see _pppp_rrrr_cccc_tttt_llll(2)] has been enabled then all remaining members of the share group will be signaled. By default, standard C library routines such as _pppp_rrrr_iiii_nnnn_tttt_ffff and _mmmm_aaaa_llll_llll_oooo_cccc function properly even though two or more shared processes access them simultaneously. To accomplish this, a special arena is set up [see _uuuu_ssss_iiii_nnnn_iiii_tttt(3P)] to hold the locks and semaphores required. Unless the PPPPRRRR____NNNNOOOOLLLLIIIIBBBBCCCC flag is present, the parent will initialize and each child will join the C library arena. Arenas have a configurable maximum number of processes that can join, that is set when the arena is first created. This maximum (default 8) can be configured using _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P). Each process in the share group needs access to this arena and requires a single file lock [see _ffff_cccc_nnnn_tttt_llll(2)]. This may require more file locks to be configured into the system than the default system configuration provides. Programs using share groups that are invoking system services (either system calls or lllliiiibbbbcccc routines), should be compiled with the PPPPaaaaggggeeee 4444 SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) feature test macro ____SSSSGGGGIIII____MMMMPPPP____SSSSOOOOUUUURRRRCCCCEEEE set in any file containing functions that share group members might access (see CAVEATS section below). Currently, this is only required for correct treatment of the system error value _e_r_r_n_o (see discussion below) but in the future may be required for the correct functioning of other services. _ssss_pppp_rrrr_oooo_cccc will fail and no new process will be created if one or more of the following are true: [ENOMEM] If there is not enough virtual space to allocate a new stack. The default stack size is settable via _pppp_rrrr_cccc_tttt_llll(2), or _ssss_eeee_tttt_rrrr_llll_iiii_mmmm_iiii_tttt(2). [EAGAIN] The system-imposed limit on the total number of processes under execution, {_N_P_R_O_C} [see iiiinnnnttttrrrroooo(2)], would be exceeded. [EAGAIN] The system-imposed limit on the total number of processes under execution by a single user {_C_H_I_L_D__M_A_X} [see iiiinnnnttttrrrroooo(2)], would be exceeded. [EAGAIN] Amount of system memory required is temporarily unavailable. [EINVAL] _s_p was null and _l_e_n was less than 8192. [EPERM] The system call is not permitted from a pthreaded program (see CAVEATS section below). When called with the PPPPRRRR____NNNNOOOOLLLLIIIIBBBBCCCC flag not set, in addition to the above errors _ssss_pppp_rrrr_oooo_cccc will fail and no new process will be created if one or more of the following are true: [ENOSPC] If the size of the share group exceeds the number of users specified via _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P) (8 by default). Any changes via _uuuu_ssss_cccc_oooo_nnnn_ffff_iiii_gggg(3P) must be done BEFORE the first _ssss_pppp_rrrr_oooo_cccc is performed. [ENOLCK] There are not enough file locks in the system. [EACCES] The shared arena file (located in /usr/tmp) used in conjunction with the C library could not be opened or created for read/write. _N_e_w _p_r_o_c_e_s_s _p_i_d # _c_o_u_l_d _n_o_t _j_o_i_n _I/_O _a_r_e_n_a:<..> if the new share group member could not properly join the C library arena. The new process exits with a -1. See also the possible errors from _uuuu_ssss_iiii_nnnn_iiii_tttt(3P). PPPPaaaaggggeeee 5555 SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) NNNNOOOOTTTTEEEESSSS IrisGL processes that share virtual address space will share access to the graphics hardware and associated data structures. IrisGL calls made by such processes must be single threaded to avoid simultaneous access to these resources. Furthermore, _gggg_ffff_llll_uuuu_ssss_hhhh(3G) must be called prior to leaving the critical section represented by the set of graphics calls. This manual entry has described ways in which processes created by _ssss_pppp_rrrr_oooo_cccc differ from those created by _ffff_oooo_rrrr_kkkk. Attributes and behavior not mentioned as different should be assumed to work the same way for _ssss_pppp_rrrr_oooo_cccc processes as for processes created by _ffff_oooo_rrrr_kkkk. Here are some respects in which the two types of processes are the same: The parent and child after an _ssss_pppp_rrrr_oooo_cccc each have a unique process id (_p_i_d), but are in the same process group. A signal sent to a specific _p_i_d in a share group [see _kkkk_iiii_llll_llll(2)] will be received by only the process to which it was sent. Other members of the share group will not be affected. A signal sent to an entire process group will be received by all the members of the process group, regardless of share group affiliations [see _kkkk_iiii_llll_llll_pppp_gggg(3B)]. See _pppp_rrrr_cccc_tttt_llll(2) for ways to alter this behavior. If the child process resulting from an _ssss_pppp_rrrr_oooo_cccc dies or calls _eeee_xxxx_iiii_tttt(2), the parent process receives the SIGCLD signal [see _ssss_iiii_gggg_ssss_eeee_tttt(2), _ssss_iiii_gggg_aaaa_cccc_tttt_iiii_oooo_nnnn(2), and _ssss_iiii_gggg_vvvv_eeee_cccc(3B)]. CCCCAAAAVVVVEEEEAAAATTTTSSSS Removing virtual space (e.g. unmapping a file) is an expensive operation and forces all processes in the share group to single thread their memory management operations for the duration of the unmap system call. The reason for this is that the system must insure that no other processes in the share group can reference the virtual space that is being removed or the underlying physical pages during or after the removal. To accomplish this, the system memory management code does the following: Locks a lock on the share group that prevents any other process in the group from doing any memory management operations (page faults, protection faults, second level TLB misses, _mmmm_mmmm_aaaa_pppp(2), _mmmm_uuuu_nnnn_mmmm_aaaa_pppp(2), _ssss_bbbb_rrrr_kkkk(2)). Sends TLB shootdown interrupts to all other cpus in the system that cause them to remove any entries from the processor's Translation Lookaside Buffer (TLB) for the share group for the address range being deleted. Removes the virtual mapping from the share group's memory management data structures and frees any underlying physical pages. Releases the lock to allow parallel operations to continue. PPPPaaaaggggeeee 6666 SSSSPPPPRRRROOOOCCCC((((2222)))) SSSSPPPPRRRROOOOCCCC((((2222)))) _pppp_iiii_xxxx_iiii_eeee(1) and _pppp_rrrr_oooo_ffff(1) do not work on processes that call _ssss_pppp_rrrr_oooo_cccc and do not share address space (i.e. PPPPRRRR____SSSSAAAADDDDDDDDRRRR is not set). Note that the global variable _e_r_r_n_o is normally a single location shared by all processes in a share group in which address space is a shared attribute. This means that if multiple processes in the group make system calls or other library functions which set _e_r_r_n_o, the value of _e_r_r_n_o is no longer useful, since it may be overwritten at any time by a call in another process in the share group. To have each thread have its own private version of _e_r_r_n_o, programs should be compiled with the feature test macro ____SSSSGGGGIIII____MMMMPPPP____SSSSOOOOUUUURRRRCCCCEEEE defined before including the header file _e_r_r_n_o._h. Note however that some system supplied libraries have not been converted to set the per-thread error value - they will only set the global error value. This will be corrected in future releases. This means an application compiled with ______SSSS_GGGG_IIII______MMMM_PPPP______SSSS_OOOO_UUUU_RRRR_CCCC_EEEE and directly referencing _e_r_r_n_o will reference the per-thread error value and not get the global error value that a non-converted library might have set. There are two workarounds to this problem: 1) define the feature test macro ______SSSS_GGGG_IIII______MMMM_PPPP______SSSS_OOOO_UUUU_RRRR_CCCC_EEEE only in files that test _e_r_r_n_o as the result of an error from a function defined in _l_i_b_c, _l_i_b_w, _l_i_b_m, _l_i_b_a_d_m, _l_i_b_g_e_n, or _l_i_b_m_a_l_l_o_c; or 2) for accesses of _e_r_r_n_o in response to errors from functions not in one of the above mentioned libraries, call _gggg_oooo_ssss_eeee_rrrr_rrrr_oooo_rrrr(3C) (which always returns the global error value). _pppp_eeee_rrrr_rrrr_oooo_rrrr(3C) always reads the 'appropriate' error value so for a threaded application it will read the per-thread value. This means that threaded programs that call errno setting functions in non-converted libraries and attempt to have _pppp_eeee_rrrr_rrrr_oooo_rrrr print out the error will not get the correct error value. In this case _s_t_r_e_r_r_o_r(_g_o_s_e_r_r_o_r()) should be used instead. _rrrr_llll_dddd(1) does not support execution of _ssss_pppp_rrrr_oooo_cccc during shared object initialization, such as that described under the -init flag to _llll_dddd(1). In particular, C++ users must take care that their code does not contain global objects which have constructors which call _ssss_pppp_rrrr_oooo_cccc(2). Should _ssss_pppp_rrrr_oooo_cccc(2) be called during object initialization, results will generally be non-deterministic and unpredictable. The _ssss_pppp_rrrr_oooo_cccc model of threading is incompatible with POSIX threads. Attempts to create an sproc process from a pthreaded program will be rejected [see _pppp_tttt_hhhh_rrrr_eeee_aaaa_dddd_ssss(5)]. SSSSEEEEEEEE AAAALLLLSSSSOOOO blockproc(2), fcntl(2), fork(2), intro(2), prctl(2), setrlimit(2), goserror(3C), oserror(3C), pcreate(3C), pthreads(5), usconfig(3P), usinit(3P), rld(1), ld(1). DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS Upon successful completion, _ssss_pppp_rrrr_oooo_cccc returns the process id of the new process. Otherwise, a value of -1 is returned to the calling process, and _e_r_r_n_o is set to indicate the error. PPPPaaaaggggeeee 7777